Adding some docs for libprimis headers #24
Conversation
| @@ -105,6 +105,10 @@ struct Slot | |||
| } | |||
|
|
|||
| virtual const char *name() const; | |||
|
|
|||
| /** | |||
| * @brief The directory where textures are stored | |||
There was a problem hiding this comment.
The convention I've used for @brief statements is a complete sentence ending with a period. I also would generally phrase the @brief for this as "returns the directory..." since that is more specifically what the function does, and then use the current phrase for the @return.
| /** | ||
| * @brief Extract or replace the shader parameter name, inserting if it doesn't exist, in `shaderparams`. | ||
| * | ||
| * Extracts the name from a global `shaderparams` whose type is `std::unordered_set<std::string>`. |
There was a problem hiding this comment.
Technically this global is called shaderparamnames.
For some additional context, this global set of shaderparamnames is only used by this function, is not cleaned up at any point, and is used specifically to assign the SlotShaderParam::name field. This object is used when handling map loading (when most slots are initialized) and when slot params are added while editing ( setshaderparam and reuseuniformparam CS commands).
| * If the name doesn't exist yet, it is inserted, then returned | ||
| * | ||
| * @param name The name to retrieve | ||
| * @param insert A bool value representing wether or not to replace it in the global shaderparams global; default true |
| * Extracts the name from a global `shaderparams` whose type is `std::unordered_set<std::string>`. | ||
| * It performs the necessary "conversion" from `std::string` to `const char *`. | ||
| * | ||
| * If the name doesn't exist yet, it is inserted, then returned |
There was a problem hiding this comment.
If the name doesn't exist yet or insert is true then the value will be inserted.
It appears that due to the specific behavior of unordered_set<std::string> compared to hashset<const char *> that this may be redundant, since strings which compare equal under strcmp or std::string::operator== can be allocated independent entries in a hashset<const char *> (or unordered_set<const char *>) but not in an unordered_set<std::string>. I'd need to do testing to verify this behavior.
Ongoing PR branching from main to add some documentation to functions in the headers library.
Suggestions and corrections are welcome